Filtering, Sorting, and Pagination

Data API query controls are JSON or scalar query-string parameters. Encode them through your HTTP library instead of concatenating them into a URL by hand.

GET/api/v1/data/{provider}/{dataset}/

Parameters

Name	Type	Requirement	Description
query	JSON object	Optional	Conditions that records must match. Most customer requests include an asset_id or company_id.
sort	JSON object	Optional	Sort fields and directions. Use 1 for ascending and -1 for descending.
limit	Integer	Required	Number of records to return, from 1 through 10,000.
skip	Integer	Optional	Number of matching records to skip. Defaults to 0.
fields	String	Optional	Comma-separated fields to return.
include_count	Boolean	Optional	Adds the total number of matching documents to the Total response header.

Filter records

{
  "asset_id": 12345,
  "timestamp": { "$gt": 1710000000 }
}

Pass the object through your client's parameter encoder:

params = {
    "query": json.dumps({
        "asset_id": 12345,
        "timestamp": {"$gt": 1710000000},
    }),
    "limit": 1000,
}

Sort records

params["sort"] = json.dumps({"timestamp": 1})   # Oldest first
params["sort"] = json.dumps({"timestamp": -1})  # Newest first

Choose a field supported by the dataset's indexes. Sorting on an unindexed field can produce a slow request or timeout.

Select fields

Return only values needed by the integration:

params["fields"] = "timestamp,asset_id,data.hole_depth,data.bit_depth"

Field selection reduces response size and parsing work.

Page through time-series data

For large time-series exports, prefer cursor-style pagination using the last timestamp instead of increasing skip indefinitely:

1. Sort by timestamp ascending.
2. Request up to 10,000 records.
3. Record the last returned timestamp.
4. Add timestamp: {"$gt": last_timestamp} to the next query.
5. Stop when the API returns an empty array.

If multiple records can share a timestamp, include a second stable field in the sort and cursor strategy to avoid duplicates or gaps.